home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / klibloader.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  14.8 KB  |  406 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 1999 Torben Weis <weis@kde.org>
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License version 2 as published by the Free Software Foundation.
  7.  
  8.    This library is distributed in the hope that it will be useful,
  9.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.    Library General Public License for more details.
  12.  
  13.    You should have received a copy of the GNU Library General Public License
  14.    along with this library; see the file COPYING.LIB.  If not, write to
  15.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.    Boston, MA 02110-1301, USA.
  17. */
  18. #ifndef KLIBLOADER_H
  19. #define KLIBLOADER_H
  20.  
  21. #include <qobject.h>
  22. #include <qstring.h>
  23. #include <qstringlist.h>
  24. #include <qasciidict.h>
  25. #include <qptrlist.h>
  26. #include <kglobal.h>
  27.  
  28. #include <stdlib.h> // For backwards compatibility
  29.  
  30. class KInstance;
  31. class QTimer;
  32. class KLibrary;
  33. class KLibFactory;
  34. class KLibFactoryPrivate;
  35. class KLibLoaderPrivate;
  36. class KLibraryPrivate;
  37.  
  38. # define K_EXPORT_COMPONENT_FACTORY( libname, factory ) \
  39.     extern "C" { KDE_EXPORT void *init_##libname() { return new factory; } }
  40.  
  41. /**
  42.  * @short Represents a dynamically loaded library.
  43.  *
  44.  * KLibrary allows you to look up symbols of the shared library.
  45.  * Use KLibLoader to create a new instance of KLibrary.
  46.  *
  47.  * @see KLibLoader
  48.  * @author Torben Weis <weis@kde.org>
  49.  */
  50. class KDECORE_EXPORT KLibrary : public QObject
  51. {
  52.     friend class KLibLoader;
  53.     friend class QAsciiDict<KLibrary>;
  54.  
  55.     Q_OBJECT
  56. public:
  57.     /**
  58.      * Don't create KLibrary objects on your own. Instead use KLibLoader.
  59.      */
  60.     KLibrary( const QString& libname, const QString& filename, void * handle );
  61.  
  62.     /**
  63.      * Returns the name of the library.
  64.      * @return The name of the library like "libkspread".
  65.      */
  66.     QString name() const;
  67.  
  68.     /**
  69.      * Returns the file name of the library.
  70.      * @return The filename of the library, for example "/opt/kde2&/lib/libkspread.la"
  71.      */
  72.     QString fileName() const;
  73.  
  74.     /**
  75.      * Returns the factory of the library.
  76.      * @return The factory of the library if there is any, otherwise 0
  77.      */
  78.     KLibFactory* factory();
  79.  
  80.     /**
  81.      * Looks up a symbol from the library. This is a very low level
  82.      * function that you usually don't want to use. Usually you should
  83.      * check using hasSymbol() whether the symbol actually exists,
  84.      * otherwise a warning will be printed.
  85.      * @param name the name of the symbol to look up
  86.      * @return the address of the symbol, or 0 if it does not exist
  87.      * @see hasSymbol
  88.      */
  89.     void* symbol( const char* name ) const;
  90.  
  91.     /**
  92.      * Looks up a symbol from the library. This is a very low level
  93.      * function that you usually don't want to use.
  94.      * Unlike symbol(), this method doesn't warn if the symbol doesn't exist,
  95.      * so if the symbol might or might not exist, better use hasSymbol() before symbol().
  96.      * @param name the name of the symbol to check
  97.      * @return true if the symbol exists
  98.      * @since 3.1
  99.      */
  100.     bool hasSymbol( const char* name ) const;
  101.  
  102.     /**
  103.      * Unloads the library.
  104.      * This typically results in the deletion of this object. You should
  105.      * not reference its pointer after calling this function.
  106.      */
  107.     void unload() const;
  108.  
  109. private slots:
  110.     void slotObjectCreated( QObject *obj );
  111.     void slotObjectDestroyed();
  112.     void slotTimeout();
  113.  
  114. private:
  115.     /**
  116.      * @internal
  117.      * Don't destruct KLibrary objects yourself. Instead use unload() instead.
  118.      */
  119.     ~KLibrary();
  120.  
  121.     QString m_libname;
  122.     QString m_filename;
  123.     KLibFactory* m_factory;
  124.     void * m_handle;
  125.     QPtrList<QObject> m_objs;
  126.     QTimer *m_timer;
  127.     KLibraryPrivate *d;
  128. };
  129.  
  130. class KLibWrapPrivate;
  131.  
  132. /**
  133.  * The KLibLoader allows you to load libraries dynamically at runtime.
  134.  * Dependent libraries are loaded automatically.
  135.  *
  136.  * KLibLoader follows the singleton pattern. You can not create multiple
  137.  * instances. Use self() to get a pointer to the loader.
  138.  *
  139.  * @see KLibrary
  140.  * @author Torben Weis <weis@kde.org>
  141.  */
  142. class KDECORE_EXPORT KLibLoader : public QObject
  143. {
  144.     friend class KLibrary;
  145.  
  146.     Q_OBJECT
  147. public:
  148.     /**
  149.      * You should NEVER destruct an instance of KLibLoader
  150.      * until you know what you are doing. This will release
  151.      * the loaded libraries.
  152.      */
  153.     ~KLibLoader();
  154.  
  155.     /**
  156.      * Loads and initializes a library. Loading a library multiple times is
  157.      * handled gracefully.
  158.      *
  159.      * This is a convenience function that returns the factory immediately
  160.      * @param libname  This is the library name without extension. Usually that is something like
  161.      *                 "libkspread". The function will then search for a file named
  162.      *                 "libkspread.la" in the KDE library paths.
  163.      *                 The *.la files are created by libtool and contain
  164.      *                 important information especially about the libraries dependencies
  165.      *                 on other shared libs. Loading a "libfoo.so" could not solve the
  166.      *                 dependencies problem.
  167.      *
  168.      *                 You can, however, give a library name ending in ".so"
  169.      *                 (or whatever is used on your platform), and the library
  170.      *                 will be loaded without resolving dependencies. Use with caution.
  171.      * @return the KLibFactory, or 0 if the library does not exist or it does
  172.      *         not have a factory
  173.      * @see library
  174.      */
  175.     KLibFactory* factory( const char* libname );
  176.  
  177.     /**
  178.      * Loads and initializes a library. Loading a library multiple times is
  179.      * handled gracefully.
  180.      *
  181.      * @param libname  This is the library name without extension. Usually that is something like
  182.      *                 "libkspread". The function will then search for a file named
  183.      *                 "libkspread.la" in the KDE library paths.
  184.      *                 The *.la files are created by libtool and contain
  185.      *                 important information especially about the libraries dependencies
  186.      *                 on other shared libs. Loading a "libfoo.so" could not solve the
  187.      *                 dependencies problem.
  188.      *
  189.      *                 You can, however, give a library name ending in ".so"
  190.      *                 (or whatever is used on your platform), and the library
  191.      *                 will be loaded without resolving dependencies. Use with caution.
  192.      * @return KLibrary is invalid (0) when the library couldn't be dlopened. in such
  193.      * a case you can retrieve the error message by calling KLibLoader::lastErrorMessage()
  194.      *
  195.      * @see factory
  196.      */
  197.     virtual KLibrary* library( const char* libname );
  198.  
  199.     /**
  200.      * Loads and initializes a library. Loading a library multiple times is
  201.      * handled gracefully.   The library is loaded such that the symbols are
  202.      * globally accessible so libraries with dependencies can be loaded
  203.      * sequentially.
  204.      *
  205.      * @param name     This is the library name without extension. Usually that is something like
  206.      *                 "libkspread". The function will then search for a file named
  207.      *                 "libkspread.la" in the KDE library paths.
  208.      *                 The *.la files are created by libtool and contain
  209.      *                 important information especially about the libraries dependencies
  210.      *                 on other shared libs. Loading a "libfoo.so" could not solve the
  211.      *                 dependencies problem.
  212.      *
  213.      *                 You can, however, give a library name ending in ".so"
  214.      *                 (or whatever is used on your platform), and the library
  215.      *                 will be loaded without resolving dependencies. Use with caution.
  216.      * @return KLibrariy is invalid (0) when the library couldn't be dlopened. in such
  217.      * a case you can retrieve the error message by calling KLibLoader::lastErrorMessage()
  218.      *
  219.      * @see factory
  220.      */
  221.     KLibrary* globalLibrary( const char *name );
  222.  
  223.     /**
  224.      * Returns an error message that can be useful to debug the problem.
  225.      * Returns QString::null if the last call to library() was successful.
  226.      * You can call this function more than once. The error message is only
  227.      * reset by a new call to library().
  228.      * @return the last error message, or QString::null if there was no error
  229.      */
  230.     QString lastErrorMessage() const;
  231.  
  232.     /**
  233.      * Unloads the library with the given name.
  234.      * @param libname  This is the library name without extension. Usually that is something like
  235.      *                 "libkspread". The function will then search for a file named
  236.      *                 "libkspread.la" in the KDE library paths.
  237.      *                 The *.la files are created by libtool and contain
  238.      *                 important information especially about the libraries dependencies
  239.      *                 on other shared libs. Loading a "libfoo.so" could not solve the
  240.      *                 dependencies problem.
  241.      *
  242.      *                 You can, however, give a library name ending in ".so"
  243.      *                 (or whatever is used on your platform), and the library
  244.      *                 will be loaded without resolving dependencies. Use with caution.
  245.      */
  246.     virtual void unloadLibrary( const char *libname );
  247.  
  248.     /**
  249.      * Returns a pointer to the factory. Use this function to get an instance
  250.      * of KLibLoader.
  251.      * @return a pointer to the loader. If no loader exists until now
  252.      *         then one is created.
  253.      */
  254.     static KLibLoader* self();
  255.  
  256.     /**
  257.      * @internal
  258.      * Internal Method, called by the KApplication destructor.
  259.      * Do not call it.
  260.      * This is what makes it possible to rely on ~KLibFactory
  261.      * being called in all cases, whether the library is unloaded
  262.      * while the application is running or when exiting.
  263.      */
  264.     static void cleanUp();
  265.  
  266.     /**
  267.      * Helper method which looks for a library in the standard paths
  268.      * ("module" and "lib" resources).
  269.      * Made public for code that doesn't use KLibLoader itself, but still
  270.      * wants to open modules.
  271.      * @param name of the library. If it is not a path, the function searches in
  272.      *             the "module" and "lib" resources. If there is no extension,
  273.      *             ".la" will be appended.
  274.      * @param instance a KInstance used to get the standard paths
  275.      */
  276.     static QString findLibrary( const char * name, const KInstance * instance = KGlobal::instance() );
  277.  
  278. protected:
  279.     KLibLoader( QObject* parent = 0, const char* name = 0 );
  280.  
  281. private slots:
  282.     void slotLibraryDestroyed();
  283. private:
  284.     void close_pending( KLibWrapPrivate * );
  285.     QAsciiDict<KLibWrapPrivate> m_libs;
  286.  
  287.     static KLibLoader* s_self;
  288.  
  289. protected:
  290.     virtual void virtual_hook( int id, void* data );
  291. private:
  292.     KLibLoaderPrivate *d;
  293. };
  294.  
  295. /**
  296.  * If you develop a library that is to be loaded dynamically at runtime, then
  297.  * you should return a pointer to your factory. The K_EXPORT_COMPONENT_FACTORY
  298.  * macro is provided for this purpose:
  299.  * \code
  300.  *   K_EXPORT_COMPONENT_FACTORY( libkspread, KSpreadFactory )
  301.  * \endcode
  302.  *
  303.  * The first macro argument is the name of your library, the second specifies the name
  304.  * of your factory.
  305.  *
  306.  * NOTE: you probably want to use KGenericFactory<PluginClassName>
  307.  * instead of writing your own factory.
  308.  *
  309.  * In the constructor of your factory you should create an instance of KInstance
  310.  * like this:
  311.  * \code
  312.  *     s_global = new KInstance( "kspread" );
  313.  * \endcode
  314.  * This KInstance is comparable to KGlobal used by normal applications.
  315.  * It allows you to find resource files (images, XML, sound etc.) belonging
  316.  * to the library.
  317.  *
  318.  * If you want to load a library, use KLibLoader. You can query KLibLoader
  319.  * directly for a pointer to the libraries factory by using the KLibLoader::factory()
  320.  * function.
  321.  *
  322.  * The KLibFactory is used to create the components, the library has to offer.
  323.  * The factory of KSpread for example will create instances of KSpreadDoc,
  324.  * while the Konqueror factory will create KonqView widgets.
  325.  * All objects created by the factory must be derived from QObject, since QObject
  326.  * offers type safe casting.
  327.  *
  328.  * KLibFactory is an abstract class. Reimplement the
  329.  * createObject() method to give it functionality.
  330.  *
  331.  * @author Torben Weis <weis@kde.org>
  332.  */
  333. class KDECORE_EXPORT KLibFactory : public QObject
  334. {
  335.     Q_OBJECT
  336. public:
  337.     /**
  338.      * Create a new factory.
  339.      * @param parent the parent of the QObject, 0 for no parent
  340.      * @param name the name of the QObject, 0 for no name
  341.      */
  342.     KLibFactory( QObject* parent = 0, const char* name = 0 );
  343.     virtual ~KLibFactory();
  344.  
  345.     /**
  346.      * Creates a new object. The returned object has to be derived from
  347.      * the requested classname.
  348.      *
  349.      * It is valid behavior to create different kinds of objects
  350.      * depending on the requested @p classname. For example a koffice
  351.      * library may usually return a pointer to KoDocument.  But
  352.      * if asked for a "QWidget", it could create a wrapper widget,
  353.      * that encapsulates the Koffice specific features.
  354.      *
  355.      * create() automatically emits a signal objectCreated to tell
  356.      * the library about its newly created object.  This is very
  357.      * important for reference counting, and allows unloading the
  358.      * library automatically once all its objects have been destroyed.
  359.      *
  360.      * @param parent the parent of the QObject, 0 for no parent
  361.      * @param name the name of the QObject, 0 for no name
  362.      * @param classname the name of the class
  363.      * @param args a list of arguments
  364.      */
  365.  
  366.      QObject* create( QObject* parent = 0, const char* name = 0, const char* classname = "QObject", const QStringList &args = QStringList() );
  367.  
  368. signals:
  369.     /**
  370.      * Emitted in #create
  371.      * @param obj the new object
  372.      */
  373.     void objectCreated( QObject *obj );
  374.  
  375.  
  376. protected:
  377.  
  378.     /**
  379.      * Creates a new object. The returned object has to be derived from
  380.      * the requested classname.
  381.      *
  382.      * It is valid behavior to create different kinds of objects
  383.      * depending on the requested @p className. For example a koffice
  384.      * library may usually return a pointer to KoDocument.  But
  385.      * if asked for a "QWidget", it could create a wrapper widget,
  386.      * that encapsulates the Koffice specific features.
  387.      *
  388.      * This function is called by #create()
  389.      * @param parent the parent of the QObject, 0 for no parent
  390.      * @param name the name of the QObject, 0 for no name
  391.      * @param className the name of the class
  392.      * @param args a list of arguments
  393.      */
  394.     virtual QObject* createObject( QObject* parent = 0, const char* name = 0,
  395.                                    const char* className = "QObject",
  396.                                    const QStringList &args = QStringList() ) = 0;
  397.  
  398.  
  399. protected:
  400.     virtual void virtual_hook( int id, void* data );
  401. private:
  402.     KLibFactoryPrivate *d;
  403. };
  404.  
  405. #endif
  406.